Screen Manager Library - routines to read screen files, paint screens,
control windows and enter data. See Screen Manager Library 2 for
routines to create & manipulate screens and fields and to write screen
files.

Groups of function.

1. SM initialisation.
2. File/data-block opening.
3. Screen and window control and enquiry.
4. Softkey label control and enquiry.
5. Data field control and enquiry
6. Event handling (filling in the fields).
7. SM termination.

All screen I/O is conducted through an intermediate set of calls - see
the file smio.h. At present only terminfo is supported but in theory,
this file could be adapted for other disciplines.

All character strings are held as the special type CHAR to ease
implementation of multi-byte character strings (ie a CHAR is not
assumed to be 7 or 8 bits except by the underlying character
manipulation support library e.g. strcpy).

A window is created automatically for function keys. If no other
windows are created then all other activity happens on 'stdscr'. As a
simplifying assumption, the only window that is refreshed is the
topmost window (most recently opened).

Screens and softkey labels are held in external ascii files or in
static storage ('blocks') in the source code of the controlling
program. Many screens and softkey labels can be held in one file or
block. Screen files and blocks are created by the 'smcreate'
interactive screen design editor (or with an editor). Lines starting
with '#' are comments. Line in external files (but not static
'blocks') may be continued with '\' at the end of the line.

Each screen or softkey label set is initially referred to by its name.
When a screen or softkey label set is opened, a handle to that entity
is returned. Screens and softkey label sets do not need to be closed
but when they are closed they release dynamic memory.

Similarly, fields are initially referred to by name (within screen
handle) and when, opened a field handle is returned. All field
manipulation and enquiry is then done with the handle. Fields cannot
be closed - they vanish when the enclosing screen is closed.

Softkey labels.

Softkey label sets provide for 8 function key labels with 16
characters in each label and are independent of the screen being
displayed. The labels are displayed as follows:

012345678901234567890123456789012345678901234567890
11111111 22222222 33333333 44444444         55555555 66666666 77777777 88888888
11111111 22222222 33333333 44444444         55555555 66666666 77777777 88888888

In this way the bottom right corner is never painted, thereby avoiding
the 'automatic hardware scroll' problem.

Each softkey can be loaded with a string - typically a command for the
application program such as 'quit' or 'previous_keys'. The default is
'f1' through 'f8'. The softkeys are assumed to be called f1 through
f8.

A softkey label can be specified to be a 'toggle' in which case the
8th character on the first line of the label is automatically toggled
between '*' and ' ' every time the function key is pressed. The
application can enquire the current status of the key as well as set
the status. ('*' == on, true or 1; ' ' = off, false or 0)

Screens.

For maximum portability, screens should not assume that more than a
total of 24 lines are available on the terminal of which 2 lines are
used as function keys labels and 22 can be used in the display. A
minimum of 80 columns is assumed. It is fair to assume that at least
some form of 'standout' is available.  Screens may also specify line
drawing, inverse video, blinking, underlined and bold text but these
features may not be portable.

Screens may be designed to be larger than the physical display or
window and the application will scroll horizontally or vertically
around the 'virtual' screen.

A screen may be defined as scrolling - the lowest line of the screen
will be repeated to the bottom of the screen less one line. If the
scrolling number is set higher then that number of lines will be left
at the bottom of the screen.

Data Field Features.

Individual data fields can be specified as:

	Integer
	Floating Point
	Fixed point (currency)
	Binary
	Octal
	Hexadecimal
	Alphabetic
	Alphanumeric
	Boolean
	International Date (DD/MM/YY - the separator can be set to any
			    character)
	US Date (MM/DD/YY - the separator can be set to any character)
	Time (hr:mn:sc - the separator can be set to any character)

Data fields can also be marked 'protected' and/or hidden. Protection
and hidden attributes can be toggled programmatically.

Data fields can be displayed with any display enhancement (the default
is 'standout').

Data fields may be wider than the physical screen but must fit into
the 'virtual' screen.

Data fields may be narrower than the data they contain - SM will
scroll automatically to accomodate them.

A numeric data field may specify a radix and separator (default '.'
and ',' respectively) which is automatically inserted as the number is
entered. The separator can be turned off by setting it to 0 (default).

Data fields may have default values which can be reinstated at any
time.

A data field may be of any length. A negative length means a maximum
length.

Navigation by the user while editing data fields is via the 'standard'
emacs control codes:

	^A start of field (also the home key)
	^B back one space (also the arrow keys)
	^D delete character (also the delete key)
	^E end of field (also the home down-end key)
	^F forward one space (also the arrow keys)
	^H destructive backspace
	^I tab to next field
	^J enter (next screen)
	^T transpose characters

If the terminal also supports 8th bit meta characters:
	M-B back a word
	M-D delete a word
	M-F forward a word
	M-T transpose words

	M-1 == F1
	.      .
	.      .
	M-8 == F8

Routines to write screen files and create/manipulate screen & data
structures. See Screen Manager Library 1 for routines for simpler
functions - read & display screen files, enter data etc.

Groups of function.

1. Write screen file.
2. Screen manipulation:
	a. Create named screen structure.
	b. Change name of screen.
	c. Add a character to the screen at a given location.
3. Softkey Manipulation:
	a. Create a named softkey label set.
	b. Change the name of a softkey label set.
	c. Set the value of one label in a softkey label set.
4. Data field manipulation
	a. Create a named field in the current screen.
	b. Change the name of a field.
	c. Set the display width of a field.
	d. Set the data type of a field.
	e. Set the default value for the field.
	f. Set the starting location for the field.


